<html>
<head>
<title>GWT Masterview library documentation: Overview</title>
<link href="resources/main.css" rel="stylesheet" type="text/css" />
<link rel="stylesheet" href="resources/SyntaxHighlighter.css" type="text/css" />
<script src="resources/shCore.js"></script>
<script src="resources/shBrushJava.js"></script>
<script>
    window.onload = function() {
      dp.SyntaxHighlighter.HighlightAll("code");
    }
</script>

</head>
<body>
<div id="header">
<h1>Masterview library 0.1</h1>
</div>

<div id="navigation">
<h2>Choose topic:</h2>
<ul>
	<li><a href="index.html">Overview</a></li>
	<li><a href="basic-usage.html">Getting started guide</a></li>
	<li><a href="themes.html">Styling the tables</a></li>	
	<li><a href="filtering-expressions.html">Filtering</a></li>
</ul>
</div>

<div id="content">
<h1>Overview</h1>
<p>Masterview library is an extension to Google Web Toolkit that provides widgets to
filter, sort and paginate your data. It's easy to use, fast and works right out of the box: you 
can display your JavaBeans with just 3-4 lines of code.</p>

<p>Initially I started to look for a replacement to the <a href="http://displaytag.sourceforge.net">Displaytag library</a>, which can't
be used in pure GWT applications. Some GWT-extending libraries provided tables, but these tables either were
just wrappers of external JavaScript toolkits, or didn't have filter or paging functionality. So I 
wrote my own small library, with API similar to the one that Displaytag has, and named it Masterview, 
because I find it simple to create master screens using it.</p>

<p>A tutorial on how to start using the library can be found <a href="basic-usage.html">here</a>.

<p>Masterview library has several predefined themes, but default one looks like this (you can read
more about using predefined themes or creating your own <a href="themes.html">here</a>):</p>

<div style="text-align:center;">
	<img src="resources/screenshot.png"/>
</div>

<h2>The main features of the library</h2>
<ul>
<li>The Masterview library, opposing to many other GWT libraries made of wrappers, uses no external JavaScript, 
only extending basic GWT widgets. It has several advantages:
	<ul>
		<li>Smooth integration with standart GWT widgets and their extensions.</li>
		<li>Easy debugging in browser hosted mode.</li>
		<li>Advantage of GWT compiler's awesome optimization that improves from version to version.</li>
	</ul>
</li>
<li>The API is similar to the one Displaytag library has. The only difference is that you write Java code instead of jsp tags.
For example, instead of writing something like this
<textarea name="code" class="java:nogutter:nocontrols" rows="15" cols="100">
<display:table name="people" pagesize="16">
	<display:column property="firstName" title="First name" sortable="false"  style="width: 40%"/>
	<display:column property="lastName" title="Last name" sortable="true" style="width: 60%"/>
</display:table>
</textarea> 
you'll write
<textarea name="code" class="java:nogutter:nocontrols" rows="15" cols="100">
MasterView masterView = GWT.create(Person.class);
masterview.setItems(people);
masterview.appendColumn(new Column("firstName", "First name", false, "40%");
masterview.appendColumn(new Column("lastName", "Last name", true, "60%");
RootPanel.get().add(masterview);
</textarea>
</li>
<li>You don't have to rewrite any existing code, except one thing: you need to mark beans that are to be displayed in a table 
with IsDisplayable interface. After that the library will create your table with the help of GWT's generators.</li>
<li>Library is provided with a number of default themes (todo: add some good-looking themes).</li>
<li>Library is (todo) localizable (not fully supported yet).</li>
<li>Built-in paging and sorting.</a>
<li>Items can be filtered based on simple regular expressions (your can read about it <a href="filtering-expressions.html">here</a>).</li>
</ul>

<h2>The limitations of the library</h2>
<ul>
	<li>If you want to display a bean, which has associated bean as a property, than you can't display 
	properties of the associated bean. For example, if there is a <i>Person</i> bean with a <i>getAddress()</i> method that
	returns an Address bean, it's not possible to display <i>city</i> property of the Address bean like that:
	<textarea name="code" class="java:nogutter:nocontrols" rows="15" cols="100">
		MasterView masterView = GWT.create(Person.class);		
		masterview.appendColumn(new Column("address.city", "Person's city", true, "100%");
	</textarea>
	One possible solution (if there is an absolute need to display person's city in a table) is to add <i>getCity()</i> method 
	to <i>Person</i> bean with code like this:
	<textarea name="code" class="java:nogutter:nocontrols" rows="15" cols="100">
		public String getCity() {
			Address address = getAddress();
			if (null == address) {
				return "---"; //or something
			}
			
			return address.getCity();
		}
	</textarea>
	and create the grid's column like this:
	<textarea name="code" class="java:nogutter:nocontrols" rows="15" cols="100">		
		MasterView masterView = GWT.create(Person.class);		
		masterview.appendColumn(new Column("city", "Person's city", true, "100%");		
	</textarea>
	</li>
</ul>
</div>
</body>
</html>